Magnum One

home *** CD-ROM | disk | FTP | other *** search

/ Magnum One / Magnum One (Mid-American Digital) (Disc Manufacturing).iso / d18 / tjtot10a.arc / DOCS.EXE / arc / CHAPT9.TXT < prev next >

Wrap

Text File | 1991-05-19 | 86KB | 2,168 lines

Managing Lists "Three questions are essential... What is the author's object? How far has he accomplished it? How far is that object worthy of approbation? Nathanial P Willis Introduction Lists, lists, lists. Our lives and our software are often dominated by lists. The Toolkit provides three powerful units to help you manage software lists. (Your lives are your own responsibility!) In this chapter, the totLINK and totLIST units are discussed in detail. totLINK provides objects to help you maintain and sort large lists, and totLIST provides objects for displaying lists and arrays in windows. A common form of software list is a file directory list. The Toolkit provides two flexible directory displaying objects, and these are dis- cussed in the next chapter. Array and Linked List Theory One-dimensional arrays provide a very quick and convenient way of managing lists. An array is a data structure designed to store data about a fixed number of identical elements. For example, the following variable could be used to store the address of my two sisters' and three brothers' addresses: Addresses: array [1..5] of string; Data in the array is accessed by specifying the element number. For example, the following statement would update my second sister's address: Addresses[2] := "38 The Ridgeway, Friern Barnet, London" Arrays are very easy to create, but suffer from two major weaknesses: q The size of an array is fixed at compile time. In other words, in your source code you must explicitly state the size (or bounds) of the array. In our simple example, this was not a problem because I have only five siblings. Imagine, however, that you need to write a generic name and address program. You don't know how many names and addresses will be required, but you must spec- ify the number in your program. The typical solution is to choose a large number of elements (e.g. 200) and hope that the user doesn't need more. Not only does this set a limit on the pro- gram's capacity, it also wastes memory if the maximum number of 9-2 User's Guide -------------------------------------------------------------------------------- elements are not used. Turbo Pascal automatically allocates the memory for the entire array regardless of how many elements are actually used. Which leads us to the second shortcoming. q The maximum size of a program's data segment in Turbo Pascal is 64k. This means that the sum of all the program's global vari- ables cannot exceed 64k, and, therefore, no individual data structure can exceed 64k. In our example, each element of the array consumed 256 bytes, so 256 of these elements would consume the entire data segment leaving no room for other global vari- ables. Linked lists do not suffer from these shortcomings. With a linked list, each element is stored independently. The first element in the list includes a pointer indicating where the second element in the list is stored. The second element in the list includes a pointer to the loca- tion of the third element in the list, and so on. When you reach an element in the list that points to NIL, you know you have reached the end of the list. You do not need to fix the maximum number of elements in the list at compile time. Furthermore, the data is stored on the heap (not in the data segment) and so is not limited to 64k. The list can use all of the available memory. Although linked lists are very flexible, they can prove complicated to program and manage. Fortunately, the Toolkit provides a very powerful object which makes managing linked lists a breeze. Managing Linked Lists The totLINK unit includes the object DLLOBJ. This object provides a variety of methods for creating and managing linked lists. If you are interested, DLLOBJ actually maintains a doubly-linked list. Each ele- ment in the list points to the next element and the previous element. This is more efficient when you need to move up and down the list. The DLLOBJ object is designed to store raw data, i.e. untyped vari- ables. This allows you to store literally any data in a DLLOBJ object. It is important to note that DLLOBJ is an abstract object and you should not create any instances of type DLLOBJ. In this chapter, we will concentrate on a descendant object, StrDLLOBJ, designed specifically to manage lists of strings. If you want to create objects which manage other data types, all you have to do is create an object descended from DLLOBJ. In part 2: Extending the Toolkit, there is a chapter describing how to create other descendants of DLLOBJ to manage specific data types. By way of an example, it describes how to create a linked list object for managing records. Managing Lists 9-3 -------------------------------------------------------------------------------- Before exploring the StrDLLOBJ methods, you need to understand some doubly-linked-list jargon. Each element in the list is referred to as a node. Behind the scenes, the Toolkit keeps track of the location of the first node in the list, the last node in the list, and the node that was last accessed. The last-accessed node is referred to as the active node. Creating a List To create a linked list, you must declare an instance of type StrDLLOBJ and then call the Init and Add methods. The syntax of these methods is as follows: Init; This method initializes the object and must be called before the other methods. Add(Str:string): integer; This function method creates a new node in the linked list and stores it in the string Str. The node is actually created immediately follow- ing the active node. Once the node has been added, the active node is moved to point to it. The function returns an integer code - a 0 indicates success, a 1 indicates there was insufficient memory to create the node, and a 2 indicates there was enough memory to create the node, but too little memory to store the string. Ordinarily, to populate a list, all you have to do is call Init, and then make multiple calls to Add. Listed below is an extract of the demo program, DEMLK1.PAS, which stores a list of names in a linked list. var GirlFriends: StrDLLOBJ; Retcode: integer; begin with GirlFriends do begin Init; Retcode := Add('Erica'); if Retcode <> 0 then exit; Retcode := Add('Theresa'); if Retcode <> 0 then exit; Retcode := Add('Lynn'); if Retcode <> 0 then exit; Retcode := Add('Donna'); if Retcode <> 0 then exit; 9-4 User's Guide -------------------------------------------------------------------------------- Retcode := Add('Godzilla'); if Retcode <> 0 then exit; {....} end; end. To save checking the value of Retcode every time you add a node, you might check that there is enough memory available for all the nodes, and ignore the return code, as follows: var GirlFriends: StrDLLOBJ; Retcode: integer; begin with GirlFriends do begin Init; if maxavail > 200 then begin Retcode := Add('Erica'); Retcode := Add('Theresa'); Retcode := Add('Lynn'); Retcode := Add('Donna'); Retcode := Add('Godzilla'); {...} end; end; end. In fact, if you are using Turbo Pascal 6.0 and the extended compiler directive {$X+} has been set, you can ignore the function return value, as follows: {$X+} var GirlFriends: StrDLLOBJ; begin with GirlFriends do begin Init; if maxavail > 200 then begin Add('Erica'); Add('Theresa'); Add('Lynn'); Add('Donna'); Add('Godzilla'); Managing Lists 9-5 -------------------------------------------------------------------------------- {...} end; end; end. Maintaining a List Once you have created a list, the following methods can be used to navigate the list: TotalNodes: longint; This function method returns a longint identifying the total number of nodes in the list. ActiveNodeNumber: longint; Returns the position of the active node. Jump(NodeNumber: longint) This method moves the ActiveNodePtr to the specified node number. Add inserts a node after the active node pointer. So, to insert a node anywhere in the list, call the method Jump to move the active node pointer and then call Add. Advance(Amount: longint); Moves the active node down the list the specified number of nodes. If there are insufficient nodes, the active node pointer is moved to the end of the list. Retreat(Amount: longint); Moves the active node up the list the specified number of nodes. If there are too few nodes, the active node pointer is moved to the begin- ning of the list. Advanced List Management In many programs, all you'll need to do is create a list, add items to the list, and then display the list using one of the browse or list displaying objects (discussed later). However, if you want to delete items from the list, swap the positions of two items in the list, or change an item in the list, you will need to access the nodes in the list directly. 9-6 User's Guide -------------------------------------------------------------------------------- Each node in the list is actually a DLLNodeOBJ object, and many of the list manipulation methods access a pointer to the node known as a DLLNodePtr. Without worrying about the details, all you need to know is how to determine the value of DLLNodePtr for any given node. The following four function methods serve this purpose: NodePtr(NodeNumber:longint): DLLNodePtr; Pass this function a node number, and it will return a pointer to the node. ActiveNodePtr: DLLNodePtr; Returns a pointer to the active node. StartNodePtr: DLLNodePtr; Returns a pointer to the first node in the list. EndNodePtr: DLLNodePtr; Returns a pointer to the last node in the list. Having established the DLLNodePtr value, the following methods can be used to manipulate the node data: Change(Node:DLLNodePtr;Str:string):integer; Changes the value at the node to Str. This function method returns an integer to indicate whether the change was a success: 0 indicates suc- cess, 2 indicates insufficient memory for the data, and 3 indicates an invalid node pointer. DelNode(Node:DLLNodePtr); Deletes the node. SwapNodes(Node1,Node2:DLLNodePtr); Swaps the data assigned to the two nodes. InsertBefore(Node:DLLNodePtr; Str:string); Managing Lists 9-7 -------------------------------------------------------------------------------- Inserts a new node immediately before the specified node. (The Add method inserts the data after the active node.) This method provides a way of inserting a node at the very beginning of the list. After this method has been called, the active node pointer is set to the first node in the list. GetStr(Node:DLLNodePtr; Start,Finish:longint): string; This function returns a sub-string of the data stored at the specified node. The parameters Start and Finish indicate the starting and ending characters to be extracted in the string. For example, values of 6 and 10 will return five characters commencing with the character in posi- tion 6 of the string. Pass values of zero for the Start and Finish parameters, if you want the entire string. Sort(SortID: shortint; Ascending: boolean); This powerful method rearranges the order of all the nodes in a list, i.e. it sorts the list. The sort routine is generic and can be utilized by any descendant of the DLLOBJ object. In the case of StrDLLOBJ, the first parameter has no meaning, and should be set to one. If you want the list sorted in ascending order (i.e. lowest first), pass TRUE as the second parameter, otherwise pass FALSE. Listed below is the demo program DEMLK2.PAS which illustrates many of the methods discussed thus far. Figure 9.1 shows the generated output. Program DemoLinkTwo; {DEMLK2 - creating a linked list} Uses CRT, totLink; var GirlFriends: StrDLLOBJ; Retcode: integer; I : integer; begin ClrScr; with GirlFriends do begin Init; if maxavail > 200 then begin Retcode := Add('Erica'); Retcode := Add('Theresa'); Retcode := Add('Lynn'); Retcode := Add('Donna'); Retcode := Add('Godzilla'); 9-8 User's Guide -------------------------------------------------------------------------------- writeln('Total nodes: ',TotalNodes); writeln('Active node number: ',ActiveNodeNumber); for I := 1 to TotalNodes do writeln(GetStr(NodePtr(I),0,0)); writeln; RetCode := InsertBefore(NodePtr(4),'Joyce'); writeln('Total nodes: ',TotalNodes); writeln('Active node number: ',ActiveNodeNumber); SwapNodes(NodePtr(5),NodePtr(2)); Retcode := Change(StartNodePtr,'Ekka'); for I := 1 to TotalNodes do writeln(GetStr(NodePtr(I),0,0)); writeln; writeln('Sorted:'); Sort(1,true); for I := 1 to TotalNodes do writeln(GetStr(NodePtr(I),0,0)); end; end; end. Figure 9.1 [SCREEN] Using StrDLLOBJ Removing a List Calling the method Done will always dispose of all the memory consumed by a list. A list can also be emptied with the following method: EmptyList; Removes all the memory allocated on the heap by chaining back through the list and disposing of each node. The ActiveNodePtr, StartNodePtr and EndNodePtr are set to nil, and TotalNodes is set to nil. Comparing StrDLLOBJ to Arrays If you have never used linked lists before, but you have used arrays, you might be interested in comparing array commands with StrDLLOBJ com- mands. Table 9.1 compares the command syntax by manipulating a list of 5 names. StrDLLOBJ String Array Managing Lists 9-9 -------------------------------------------------------------------------------- Declaring the Variable or Instance var NameList: StrDLLOBJ; var NameList: array[1..5] of string; Initializing the List NameList.Init; fillchar(NameList,sizeof(NameLis t),#0); Populating the List with NameList do NameList[1] := 'Mark'; begin NameList[2] := 'Kirk'; Retcode := Add('Mark'); NameList[3] := 'Lloyd'; Retcode := Add('Kirk'); NameList[4] := 'Charles'; Retcode := Add('LLoyd'); NameList[5] := 'Keith'; Retcode := Add('Charles'); Retcode := Add('Keith'); end; Writing an item to the display with NameList do writeln(NameList[3]); writeln(GetStr(NodePtr(3),0,0)); Swapping two items with NameList do Temp := NameList[4]; SwapNodes(NodePtr(4),NodePtr(5)); NameList[4] := NameList[5]; NameList[5] := Temp; Sorting the List NameList.Sort(1,true); Ugh! Erasing the Entries NameList.EmptyList; fillchar(NameList,sizeof(NameLis t),#0); Don't forget that the StrDLLOBJ is much more memory efficient, and is not limited to a set number of elements. Much of the power of DLLOBJ is not realized until you create descendant objects, customized for your specific needs. Refer to Part 2: Extending The Toolkit for further details. Browse Lists Whether your data is in a DLLOBJ (or descendant) object, or in a string array, you will want to take advantage of the Toolkit's objects for 9-10 User's Guide -------------------------------------------------------------------------------- automatically displaying lists in windows. In this section, the Brow- seOBJ family of objects will be discussed. These objects display lists in a scrollable window. Note that a browse window does not include a highlight bar. The user browses the contents of the list, but does not select an individual element. The ListOBJ family (discussed in the next sec- tion) provides objects for highlighting individual elements in a list. Figure 9.2 shows the object hierarchy for the BrowseOBJ family. The base object BrowseOBJ is abstract, and you should not create any instances of this type. The BrowseArrayOBJ object displays the contents of a string array, and the BrowseLinkOBJ displays the contents of an object in the DLLOBJ family. Many programs need to display the contents of ASCII files, and the object BrowseFileOBJ makes this a snap. Figure 9.2 [PICTURE] BrowseOBJ Object Hierarchy Common Methods The totLOOK unit includes an object LookTOT which is used to control the overall look and feel of applications developed with the Toolkit. Call the method LookTOT^.SetListKeys to change the keys which the user can press to close the browse window. The defaults are [KEYCAP] and [KEYCAP]. Refer to page 3-12 for further details. Because all the objects are derived from the BrowseOBJ, they share a set of common methods. The following methods can be used with any of the browse objects: SetTopPick(TopPick: longint); This method identifies the node number of the first node that will be displayed in the list window. SetStartCol(Column: longint); This method identifies the character position of the first character of the string which is visible in the list window. Managing Lists 9-11 -------------------------------------------------------------------------------- SetEndCol(Column: longint); This method sets the maximum lateral scrolling by identifying the last column which will be displayed when the window is scrolled to the right maximum. All lateral scrolling can be disabled by calling the Stretch- WinOBJ method SetScrollable (discussed later). Show; This method displays the list and immediately returns control back to the calling procedure, i.e. the Toolkit does not wait for user input. This option is useful if you want to display the list on the screen, but not activate it. Go; This method is the main "do it" method. If the list is not on display, it is drawn. The Toolkit then processes user input until an end key is pressed. LastKey:word; LastKey returns the key code of the key the user pressed to end the browse session. This is used if you need to know whether the user escaped or pressed the finish key. Done; As always, Done disposes of the Browse window object, and should always be called when the object is no longer required. Modifying the Window Characteristics The list data is displayed in a window of type StretchWinOBJ. You can modify any window attribute by directly calling the StretchWinOBJ meth- ods. BrowseOBJ includes a function method, Win, which returns a pointer to the StretchWinOBJ instance. To modify the window, call the appropriate StretchWinOBJ method using the following syntax: [BrowseOBJInstance].Win^.method For example, the following statements would change the default window size, style and title: var MyBrowser: BrowseLinkOBJ; begin with MyBrowser do begin 9-12 User's Guide -------------------------------------------------------------------------------- Init; Win^.SetSize(1,1,50,20,3); Win^.SetTitle('My Browser'); end; end. All the display colors used by the browse objects are controlled by the underlying window attributes. To change the browse display colors call the window method SetColors, e.g. Win^.SetColors(23,23,31,30); Call Win^ methods to set all the browse window characteristics, e.g. colors, title, remove status, boundaries, etc. Refer to chapter 7: Using Windows for a thorough discussion of the StretchWinOBJ methods. Browsing Arrays The BrowseArrayOBJ object provides a very simple way to browse the contents of a string array. In addition to the common methods just described, there is another method as follows: AssignList(var StrArray; Total:longint; StrLength:byte); AssignList identifies the string array that will be displayed. The three parameters are the string array, the total number of elements in the array, and the length of each string in the array. The string length parameter must reflect the string length of the array when it was declared, not the maximum length of any string assigned to the array. For example, if a string array was declared as follows: MyGirls: array[1..54] of string; then the list is assigned with the following calls: with MyBrowser do begin Init; AssignList(MyGirls,54,255); {...} end; Managing Lists 9-13 -------------------------------------------------------------------------------- Having assigned the list, all you need to do is call Show and the browse window will pop onto the display. Listed below is a the demo program DEMBR1, followed by figure 9.3 illustrating the resultant dis- play. Program DemoBrowseArrayOne; {SEMBR1} Uses DOS,CRT, totINPUT, totFAST,totLIST, totSTR; var BWin: BrowseArrayOBJ; StringList: array[1..26] of string[100]; I : integer; begin for I := 1 to 26 do {first assign something to the string array} StringList[I] := 'Line '+ IntToStr(I)+': '+ replicate(80,char(I+64)); Screen.Clear(white,'░'); {paint the screen} Key.SetFast; Key.SetClick(true); with BWin do begin Init; AssignList(StringList,26,100); Go; Done; end; end. Figure 9.3 [SCREEN] Browsing an Array The demo program DEMBR2.PAS, listed below, is very similar to DEMBR1.PAS. The only difference is that two Win^ methods are called to modify the default window settings. Figure 9.4 shows the impact on the display. Program DemoBrowseArray; Uses DOS,CRT, totFAST,totLIST, totSTR; 9-14 User's Guide -------------------------------------------------------------------------------- var BWin: BrowseArrayOBJ; StringList: array[1..26] of string[100]; I : integer; begin for I := 1 to 26 do {first assign something to the string array} StringList[I] := 'Line '+ IntToStr(I)+': ' +replicate(80,char(I+64)); Screen.Clear(white,'░'); {paint the screen} with BWin do begin Init; AssignList(StringList,26,100); Win^.SetSize(30,5,50,15,2); Win^.SetTitle('Array Browse Demo'); Go; Done; end; end. Figure 9.4 [SCREEN] Modifying the Browse Window Browsing Linked Lists The BrowseLinkOBJ is very similar to the BrowseArrayOBJ, the primary difference being that BrowseLinkOBJ displays the data stored in a DLLOBJ object rather than in an array. In addition to the common methods described, there are two additional methods as follows: AssignList(Var LinkList: DLLOBJ); This method is passed a DLLOBJ instance, or any instance of an object derived from DLLOBJ, e.g. StrDLLOBJ. ListPtr: DLLPtr; This method returns a pointer to the DLLOBJ used to create the list. You can access the linked list by using the syntax MyBrow- ser.ListPtr^.method. Listed below is the program DEMBR3.PAS, which illustrates how to build a large list of 500 items and display it in a browse window. Figure 9.5 shows the browse display. Managing Lists 9-15 -------------------------------------------------------------------------------- Program DemoBrowseList; Uses DOS,CRT, totFAST, totLINK, totLIST, totSTR; var BWin: BrowseLinkOBJ; LL : StrDLLOBJ; procedure CreateLinkedList; {} var I, Retcode : integer; begin with LL do begin Init; for I := 1 to 500 do Retcode := Add('This is line '+IntToStr(I)+ ': '+replicate(200,char(random(255)))); end; {with} end; {CreateLinkedList} begin Screen.Clear(white,'░'); {paint the screen} CreateLinkedList; with BWin do begin Init; AssignList(LL); Win^.SetTitle('List Browse Demo'); Go; Done; end; LL.Done end. Figure 9.5 [SCREEN] Browsing a StrDLLOBJ Browsing Files The BrowseFileOBJ object makes browsing ASCII text files easy. Browse- FileOBJ is descended from BrowseOBJ and inherits all the associated methods. In addition, the following method AssignFile is used to instruct the object on which file to display: 9-16 User's Guide -------------------------------------------------------------------------------- AssignFile(Filename:string): integer; This function method is passed a string indicating the name of the file to be browsed. Behind the scenes, this function loads the file from disk into a temporary StrDLLOBJ object. The function will return a 0 if the file was successfully loaded. A return value of 1 indicates that the file was not found, and so cannot be displayed. A return value of 2 indicates that there wasn't enough memory to load the entire file. In such an instance you may want to use a MessageOBJ to advise the user that only part of the file can be browsed. That's all there is to it! Just declare a BrowseFileOBJ instance and call the methods Init, AssignFile and Go: var FileWin: BrowseFileOBJ; begin with FileWin do begin Init; if AssignFile('Help.TXT') = 0 then Go; Done; end; end. The following method can be used to directly access the linked list created by the BrowseFileOBJ instance: ListPtr: StrDLLPtr; This method returns a pointer to the StrDLLOBJ used to create the list. You can access the linked list by using the syntax MyFile.ListPtr^.me- thod. Listed below is the example program, DEMBR4.PAS. This small program will display the contents of either a file specified on the command line when the program was executed, or (if no parameters were speci- fied) the contents of c:\autoexec.bat. Program DemoBrowseFile; Uses DOS,CRT, totFAST, totINPUT, totLINK, totLIST, totSTR; const DefaultFile = '\autoexec.bat'; var Managing Lists 9-17 -------------------------------------------------------------------------------- BWin: BrowseFileOBJ; RetCode: integer; Filename: string; begin Screen.Clear(white,'░'); {paint the screen} if ParamCount = 0 then FileName := DefaultFile else FileName := ParamStr(1); with BWin do begin Init; Retcode := AssignFile(Filename); if Retcode in [0,2] then Go else Writeln('Unable to load file: ',Filename,'.'); Key.DelayKey(2000); Done; end; end. 9-18 User's Guide -------------------------------------------------------------------------------- Selection Lists So far, this chapter has focused on browse windows, where the user can simply scroll data vertically and horizontally. By contrast, a list window is designed to display selectable items, much like a menu. One of the items within the list window is always highlighted, and the list may be organized into single or multiple columns. The scroll bars are used to move the item highlight bar. The list is removed when the user presses an end key such as [KEYCAP] or [KEYCAP], when the user presses [KEYCAP], or when the user double-clicks the mouse on an item. When appropriate, users may even select, or tag, multiple items from the list, and each selected item is marked with a special character. The tag status of the highlighted option can be toggled by hitting the [KEYCAP]. All items can be tagged or untagged at once by pressing [KEY- CAP] and [KEYCAP], respectively. Figure 9.6 shows a typical list window. Figure 9.6 [SCREEN] A Typical List Window By default, a list window is stretchable, and if the user changes the dimensions, the Toolkit adjusts the displayed columns and rows. Figure 9.7 is the same List window as shown in figure 9.6, after the user has stretched the window. Figure 9.7 [SCREEN] A Stretched List Window The primary Toolkit object for displaying lists in a window is ListOBJ, but this is an abstract object which should not be instanciated. Lis- tOBJ has a number of descendants designed to display different data types in lists. Figure 9.8 illustrates the ListOBJ object hierarchy. The object hierarchy is similar in principle to the BrowseOBJ hierar- chy, with the following main objects: ListArrayOBJ Displays a list derived from a string array. ListLinkOBJ Displays a list derived from any DLLOBJ object or descendant. ListDirOBJ & These two objects are used for displaying directories ListDirSortOBJ in a list window and are discussed in the next chapter. Managing Lists 9-19 -------------------------------------------------------------------------------- Figure 9.8 [PICTURE] ListOBJ Object Hierarchy Common Methods LookTOT (in the unit totLook) is used to control the overall look and feel of applications developed with the Toolkit. As well as the window- related methods, the following two LookTOT methods impact all list objects: SetListKeys Identifies the keys to globally tag or untag windows, and close the list display. SetListChars Identifies the characters which will highlight the active item, as well as the characters which identify the tagged and non-tagged items. Refer to page 3-12 for further details. Because all the list objects are derived from the ListOBJ, they share a set of common methods. The following methods can be used with any of the list objects: SetTopPick(TopPick: longint); This method identifies the node number of the first node that will be displayed in the list window, i.e. the first visible item in the list. By default, this is the first item in the list. SetActivePick(ThePick:longint); The highlighted item is referred to as the active pick. This procedure is used to set which item (or pick) will be highlighted when the list is first displayed. The passed parameter represents the number of the item in the visible window, with the top left item having a value of one. For example, if the top pick (the first visible pick) was item number 12 and you wanted to highlight the 15th item, pass a value of four. This will instruct the Toolkit to highlight the fourth visible pick. The default is the top pick. If an invalid value is used, e.g. the value is greater than the number of visible picks, the value is set to the top pick. SetTagging(On:boolean); This method is used to identify whether the user will be allowed to tag and untag items. Pass true to enable item tagging. 9-20 User's Guide -------------------------------------------------------------------------------- SetColWidth(Wid:byte); This sets the width of each column in characters. If the column width is set to zero, the list will be displayed in a single column only, and the column width will be as wide as the window. When setting the column width, remember to allow for the additional characters used to high- light the active pick, and to signify tagged and non-tagged items. Show; This method displays the list and immediately returns control to the calling procedure, i.e. the Toolkit does not wait for user input. This option is useful if you want to display the list on the screen, but not activate it. Go; This method is the main "do it" method. If the list is not on display, it is drawn. The Toolkit then processes user input until an end key is pressed. GetHiString:string; This function returns a string representing the highlighted item's data. LastKey:word; LastKey returns the key code of the key the user pressed to end the browse session. This is used if you need to know whether the user escaped or pressed the done key. Done; As always, Done disposes of the Browse window object, and should always be called when the object is no longer required. Modifying Window Characteristics Like BrowseOBJ, the list data is displayed in a window of type Stretch- WinOBJ. You can modify any window attribute by directly calling the StretchWinOBJ methods. ListOBJ includes a function method, Win, which returns a pointer to the StretchWinOBJ instance. To modify the window, call the appropriate StretchWinOBJ method using the following syntax: [ListOBJInstance].Win^.method For example, the following statements would change the default window size, style and title: Managing Lists 9-21 -------------------------------------------------------------------------------- var MyLister: ListLinkOBJ; begin with MyList do begin Init; Win^.SetSize(1,1,50,20,3); Win^.SetTitle('My Lister'); end; end. Call Win^ methods to set the list window characteristics, e.g. colors, title, remove status, boundaries, etc. Refer to chapter 7: Using Win- dows for a thorough discussion of the StretchWinOBJ methods. Note: the display colors used in list objects are controlled by two different methods. The attributes of the list window perime- ter, i.e. box, title, scroll bars and icons, are set using the method: Win^.SetColors. The display attributes for the body of the window, i.e. the items in the list, are controlled using the ListOBJ method SetColors, which is discussed later in this section. Listing Arrays The ListArrayOBJ object provides an easy way to display a list based on the contents of a string array. In addition to the common methods just described, there is the following method: AssignList(var StrArray;Total:longint; StrLength:byte;Taggable:boolean); AssignList identifies the string array that will be displayed. The four parameters are the string array, the total number of elements in the array, the length of each string in the array, and a boolean to indi- cate whether individual items can be tagged. The string length parame- ter must reflect the string length of the array when it was declared, not the maximum length of any string assigned to the array. Having assigned the list, all you need to do is call Show, and the browse window will pop onto the display. Listed below is the demo pro- gram DEMLS1.PAS. 9-22 User's Guide -------------------------------------------------------------------------------- program DemoList1; {demls1} Uses DOS, CRT, totFAST, totLIST; Var Items : array [1..20] of string[30]; ListWin: ListArrayObj; procedure FillArray; {} begin Items[1] := 'One'; Items[2] := 'Two'; Items[3] := 'Three'; Items[4] := 'Four'; Items[5] := 'Five'; Items[6] := 'Six'; Items[7] := 'Seven'; Items[8] := 'Eight'; Items[9] := 'Nine'; Items[10] := 'Ten'; Items[11] := 'Eleven'; Items[12] := 'Twelve'; Items[13] := 'Thirteen'; Items[14] := 'Fourteen'; Items[15] := 'Fifteen'; Items[16] := 'Sixteen'; Items[17] := 'Seventeen'; Items[18] := 'Eighteen'; Items[19] := 'Nineteen'; Items[20] := 'Twenty'; end; {FillArray} begin Screen.Clear(white,'░'); {paint the screen} FillArray; with ListWin do begin Init; AssignList(Items,20,30,true); Go; Done; end; end. This is a very basic list which uses all the default settings. Figure 9.9 illustrates the resultant display. Managing Lists 9-23 -------------------------------------------------------------------------------- Figure 9.9 [SCREEN] A Basic List Window The following few statements are an extract from the demo file DEMLS2.PAS which is very similar to the previous demo, except that the list window has been customized somewhat: with ListWin do begin Init; AssignList(Items,20,30,true); SetColWidth(15); Win^.SetTitle(' Pick a number! '); Win^.SetSize(24,7,55,18,2); Go; Done; end; By calling the SetColWidth method, the list has been transformed from a single list to a multi-column list. Refer back to figure 9.7 to see the output generated from DEMLS2.PAS. The program DEMLS3.PAS is yet another refinement of the array list demo. In this on-disk file, the following statement is added to change the list tagging and highlighting characters: LookTOT^.SetListChars(chr(16),chr(17),chr(14),chr(32)); Listing Linked Lists The ListLinkOBJ is very similar to the ListArrayOBJ. The primary dif- ference is that ListLinkOBJ displays the data stored in a DLLOBJ object rather than in an array. In addition to the common methods described earlier, there are the following two methods: AssignList(var LinkList: DLLOBJ); This method is passed a DLLOBJ instance, or any instance of an object derived from DLLOBJ, e.g. StrDLLOBJ. ListPtr: DLLPtr; This method returns a pointer to the DLLOBJ used to create the list. You can access the linked list by using the syntax MyList.ListPtr^.me- thod. 9-24 User's Guide -------------------------------------------------------------------------------- The demo program DEMLS4.PAS (listed below) shows how well StrDLLOBJ and ListLinkOBJ work together. This small demo program creates an StrDLLOBJ instance called ItemList. The list is populated by reading the contents of an ASCII file. The ListLinkOBJ instance ListWin is then used to display the file contents in a window. Figure 9.10 shows the generated screen display. program DemoList4; {demls4 - reading a list from a text file} Uses DOS, CRT, totFAST, totLINK, totLIST; Var ListWin: ListLinkObj; ItemList: StrDLLOBJ; FileOK: boolean; procedure LoadLinkedList; {} var F: text; Line:string; Result: integer; begin with ItemList do begin Init; {$I-} Assign(F,'demls4.txt'); Reset(F); {$I+} FileOK := (IOResult = 0); if not FileOK then Result := Add('File not found') else begin while not eof(F) do begin Readln(F,Line); Result := Add(Line); end; close(F); end; end; end; {LoadLinkedList} Managing Lists 9-25 -------------------------------------------------------------------------------- begin Screen.Clear(white,'░'); {paint the screen} LoadLinkedList; with ListWin do begin Init; AssignList(ItemList); SetColWidth(15); Win^.SetTitle(' Items from file DEMLS4.TXT '); Win^.SetSize(20,5,60,20,1); if not FileOk then SetTagging(false); Go; Done; end; ItemList.Done; end. Figure 9.10 [SCREEN] Display a List From a File Determining Which Items are Tagged Earlier you learned that by calling the method SetTagging(true), you could allow the user to tag and untag items. The Toolkit provides the method SetStatus to allow you to pre-tag (or, indeed, pre-untag!) items before the list is displayed. Similarly, the method GetStatus is used to determine the status of any item in the list. Before explaining the syntax of these methods, we need to take a little peek behind the scenes. The Toolkit stores eight different flags for each item in the list. These flags are numbered 0 through 7. Flag 0 is used to determine whether the user has tagged the item. Flag 1 indi- cates which color to use in dual color mode (discussed later). The remaining flags are not used and can be customized for descendant objects. Refer to Part 2: Extending the Toolkit for more information. The syntax of the SetStatus method is as follows: SetStatus(Pick:longint; BitPos: byte; On:boolean); To pre-tag an item, call the SetStatus method and pass three parame- ters. The first parameter specifies the item to be modified, the second parameter is the flag number (and this should be set to 0 (zero) to modify the tag flag), and the third boolean parameter should be set to True to tag the item, or False to un-tag it. 9-26 User's Guide -------------------------------------------------------------------------------- After the user has removed the list window, and before the Done method is called, the GetStatus method can be called to see which selections the user made. The syntax of GetStatus is as follows: GetStatus(Pick:longint; BitPos: byte): boolean; This function method returns true if the identified item flag is set on. The first parameter identifies the item number, and the second parameter should be set to 0 (zero) to get the status of the tag flag. The following demo program, DEMLS5.PAS, shows how to check for all the tagged items. The program writes a list of all the tagged items. program DemoList5; {demls5 - selecting all tagged items} Uses DOS, CRT, totFAST, totLINK, totLIST; Var ListWin: ListLinkObj; ItemList: StrDLLOBJ; FileOK: boolean; L,Total: longint; procedure LoadLinkedList; {} var F: text; Line:string; Result: integer; begin with ItemList do begin Init; {$I-} Assign(F,'demls4.txt'); Reset(F); {$I+} FileOK := (IOResult = 0); if not FileOK then Result := Add('File not found') else begin while not eof(F) do begin Readln(F,Line); Result := Add(Line); end; close(F); Managing Lists 9-27 -------------------------------------------------------------------------------- end; end; end; {LoadLinkedList} begin Screen.Clear(white,'░'); {paint the screen} LoadLinkedList; with ListWin do begin Init; AssignList(ItemList); SetColWidth(15); Win^.SetTitle(' Items from file DEMLS4.TXT '); Win^.SetSize(20,5,60,20,1); if not FileOk then SetTagging(false); Go; Remove; Total := ItemList.TotalNodes; clrscr; for L := 1 to Total do if GetStatus(L,0) then Writeln('Selected: ',GetString(L,0,0)); Done; end; ItemList.Done; end. In a real application, you might call a procedure to process the tagged items, rather than simply write a list of all tagged items. If you are displaying a linked list, you can take advantage of the DLLOBJ method DelAllStatus. This method is used to automatically remove entries from the list which have one of the status flags set in a specified state. The syntax of the DLLOBJ method is as follows: DelAllStatus(BitPos:byte; On:boolean); This method removes all entries from the linked list which have the specified flag set in the specified state. The first parameter indi- cates the flag number, in the range 0 to 7. The second parameter deter- mines whether all the flags set to True or False will be deleted. For example, to remove all tagged entries in a linked list you would call the method DelAllStatus(0,true);. 9-28 User's Guide -------------------------------------------------------------------------------- Displaying Dual Colored Lists All list objects are capable of displaying each item in one of two color combinations. This facility is put to good effect in the ListDi- rOBJ object (discussed in the next chapter), where the files are dis- played in one color, and the subdirectories in another. The following two methods impact the list display colors: SetColors(HAttr,NAttr,SAttr: byte); This method sets the display attributes for the items in the list. The first parameter specifies the attribute of the active pick. The other two attributes specify the attributes for the normal items. If the status (discussed below) of the normal item is set to high, the SAttr attribute will be used, otherwise the NAttr will be used. SetDualColors(On:boolean); If you want to exploit the dual color capabilities of the list objects, pass True. Passing a False will force all the items to display in the same color. The Toolkit has to have some way of identifying the status of each item, i.e. in which attribute the color should be displayed. The second of the status flags, i.e. flag 1, is designated as the color flag. The SetStatus and GetStatus flags are used to control the color feature, as follows: SetStatus(Pick:longint; BitPos: byte; On:boolean); This method is used to set the status of any item in the list. The first parameter identifies the number of the item to be set. The second parameter should be set to 1 (one) to indicate that the color status flag is being set. The final parameter is a boolean to indicate whether status is on (True) or off (False). GetStatus(Pick:longint; BitPos: byte): boolean; This function method returns true if the identified item flag is set on. The first parameter identifies the item number, and the second parameter should be set to 1 (one) to determine the status of the dual color flag. An example of the dual color facility is included in the DEMLS7.PAS, discussed in the Character Hook section at the end of the chapter. Managing Lists 9-29 -------------------------------------------------------------------------------- Displaying Messages about the Highlighted Pick The ListOBJ object family supports the optional display of a message at the bottom of the list window. This message is normally related to the currently highlighted pick. The message might be a long description of a terse pick, or some other information about the highlighted pick. There are two different ways to instruct the Toolkit to display a mes- sage. The no-fuss way is to write a special procedure (called a message hook) and instruct the Toolkit to call this procedure every time a pick is highlighted. The alternative is to take advantage of an OOP feature known as Polymorphism. Once a message displaying routine has been implemented, it can be dis- abled and enabled using the following method: SetMsgState(On:boolean); Pass True to activate the message display, or False to deactivate it. Using a Message Hook A message hook is an external function which is called every time a new pick is highlighted. To utilize the message hook facility, all you have to do is create a function following some specific rules, and then call the method SetMsgHook to instruct the Toolkit to use your function. For a function to be eligible as a message hook it must adhere to the following rules: Rule 1 The function must be declared as a FAR function. This can be achieved by preceding the function with a {$F+} compiler directive, and following the function with a {$F-} direc- tive. Alternatively, Turbo 6 users can use the new keyword FAR following the function statement. Rule 2 The function must be declared with one passed parameter of type longint. This parameter indicates the highlighted item number. Rule 3 The function must return a value of type string. This return value is the actual text to be displayed in the message area of the window display. Rule 4 The function must be at the root level, i.e. the function cannot be nested within another procedure or function. The following function declaration follows these rules: 9-30 User's Guide -------------------------------------------------------------------------------- {$F+} function MyMessageHook(HiPick:longint): string; begin ...{function statements} MyMessageHook := 'something!'; end; {$F-} The following method SetMsgHook is then called to instruct the Toolkit to call your function every time a new item is highlighted: SetMsgHook(Func:ListMsgFunc); This method is passed the function name of a function declared using the rules outlined above, e.g. SetMsgHook(MyMessageHook); The demo program DEMLS6 (listed below) implements a message hook. In this case the message is simply a phrase stating which topic is high- lighted. I hope your applications are a little more useful! Figure 9.11 illustrates the resultant output. program DemoList6; {demls6 - displaying a list message} Uses DOS, CRT, totFAST, totLINK, totLIST, totSTR, totMSG; Var ListWin: ListLinkObj; ItemList: StrDLLOBJ; FileOK: boolean; {$F+} function MsgHook(HiPick:longint):string; {} begin MsgHook := 'The Hi Pick is '+IntToStr(HiPick); end; {MsgHook} {$F-} procedure LoadLinkedList; {} var F: text; Line:string; Result: integer; begin with ItemList do Managing Lists 9-31 -------------------------------------------------------------------------------- begin Init; {$I-} Assign(F,'demls4.txt'); Reset(F); {$I+} FileOK := (IOResult = 0); if not FileOK then Result := Add('File not found') else begin while not eof(F) do begin Readln(F,Line); Result := Add(Line); end; close(F); end; end; end; {LoadLinkedList} begin Screen.Clear(white,'░'); {paint the screen} LoadLinkedList; with ListWin do begin Init; AssignList(ItemList); SetColWidth(15); SetMsgHook(MsgHook); Win^.SetTitle(' A List With Messages '); Win^.SetSize(20,5,60,20,2); Win^.SetMinSize(20,7); if not FileOk then SetTagging(false); Go; Done; end; ItemList.Done; end. Figure 9.11 [SCREEN] A List with a Mes- sage 9-32 User's Guide -------------------------------------------------------------------------------- Creating a Descendant Object By design, most of the documentation on customizing the Toolkit with object oriented techniques is to be found in Part 2: Extending the Toolkit. However, as an appetizer, this section explains how to take advantage of OOP to implement your own message method, without needing to pass a procedure as a parameter. The message hook procedure described in the previous section is perfectly adequate and acceptable, but it isn't OOP! If you want to learn a few OOP tidbits, read on, otherwise be content with the message hook and skip to the next sec- tion. Usually, to customize a Toolkit object to better meet your needs, you create a descendant object. For illustration, we will modify the List- LinkOBJ object. Whenever you create a descendant object, you should study the parent object's methods and decide which ones to replace or modify. A descendant object contains all the data and methods of its parent. As a bare minimum, you should always define new Init and Done methods, and then replace any other methods that you wish to improve or modify. (You can also add new methods, but we'll leave that to Part 2!). The ListLinkOBJ method includes the following virtual method: function MessageTask(HiPick:longint):string; VIRTUAL; This method is called every time a new topic is highlighted, and it returns the text to be displayed. Since this method is declared VIR- TUAL, we can replace the method in a descendant object, and other methods will use the newly defined version of MessageTask. The objective is to create a new object descendant from ListLinkOBJ, and replace the MessageTask method with a new routine. The syntax for declaring the new object type is as follows: Type NewListLinkOBJ = object (ListLinkOBJ) constructor Init; function MessageTask(HiPick:longint):string; VIRTUAL; destructor Done; VIRTUAL; end; {NewListLinkOBJ} The descendant object will be called NewListLinkOBJ. Notice that the special constructor and destructor procedures Init and Done are declared, as well as the new MessageTask function. The constructor and destructor methods are required when an object includes virtual meth- ods, as it instructs Turbo Pascal to manage procedure calls differ- ently. The keywords constructor and destructor are simply used as replacements for procedure. The de facto OOP standard is to name the constructor INIT and the destructor DONE. Managing Lists 9-33 -------------------------------------------------------------------------------- If the ancestor method is declared VIRTUAL, the descendant method must also be declared virtual. Furthermore, when you substitute virtual methods in a descendant object, the declaration of the method must be exactly the same as the ancestor. For this reason, MessageTask and Done are both declared virtual, with the same parameters as ListLinkOBJ. Having declared a new type NewListLinkOBJ, you must write the actual object methods in the body of your program or unit. In this case, Turbo Pascal expects the three object methods Init, MessageTask and Done. Listed below is an example of how these methods might be written. constructor NewListLinkOBJ.Init; {} begin ListLinkOBJ.Init; vMsgActive := true; end; {NewListLinkOBJ.Init} function NewListLinkOBJ.MessageTask(HiPick:longint):string; {} begin MessageTask := 'The Hi Pick is '+IntToStr(HiPick); end; {NewListLinkOBJ.MessageTask} destructor NewListLinkOBJ.Done; {} begin ListLinkOBJ.Done; end; {NewListLinkOBJ.Done} Notice that each method starts with the object name followed by a period followed by the method identifier. Whenever you declare an Init or Done method, you should always call the ancestors Init or Done -- very often, this ancestor method performs important data initialization tasks, and let's not forget that a descendant object assumes all the data of its ancestor. In the new Init method, the variable vMsgActive is set to true. (All object variables in the Toolkit commence with the letter "v".) This variable indicates that the object should always call the message dis- play method when the active topic is changed. In the LinkListOBJ, this variable defaults to false, and is changed to true when the method SetMsgHook is called. The main purpose of this descendant object is to replace the old MessageTask method with a new one. In the new method, the string value returned is just the statement identifying the high- lighted topic. That's it. Any instance of NewListLinkOBJ will automatically display the string returned by the new MessageTask method. Listed below is the example DEMLS7.PAS which shows the example in its entirety. 9-34 User's Guide -------------------------------------------------------------------------------- program DemoList7; {demls7 - creating a descendant ListObject} Uses DOS, CRT, totFAST, totLINK, totLIST, totSTR, totMSG; Type NewListLinkOBJ = object (ListLinkOBJ) {Methods...} Constructor Init; function MessageTask(HiPick:longint):string; VIRTUAL; destructor Done; VIRTUAL; end; {NewListLinkOBJ} Var ListWin: NewListLinkObj; ItemList: StrDLLOBJ; FileOK: boolean; {+++++new object methods+++++} constructor NewListLinkOBJ.Init; {} begin ListLinkOBJ.Init; vMsgActive := true; end; {NewListLinkOBJ.Init} function NewListLinkOBJ.MessageTask(HiPick:longint):string; {} begin MessageTask := 'The Hi Pick is '+IntToStr(HiPick); end; {NewListLinkOBJ.MessageTask} destructor NewListLinkOBJ.Done; {} begin ListLinkOBJ.Done; end; {NewListLinkOBJ.Done} {+++++end of new object methods+++++} procedure LoadLinkedList; {} var F: text; Line:string; Result: integer; begin with ItemList do begin Init; {$I-} Managing Lists 9-35 -------------------------------------------------------------------------------- Assign(F,'demls4.txt'); Reset(F); {$I+} FileOK := (IOResult = 0); if not FileOK then Result := Add('File not found') else begin while not eof(F) do begin Readln(F,Line); Result := Add(Line); end; close(F); end; end; end; {LoadLinkedList} begin Screen.Clear(white,'░'); {paint the screen} LoadLinkedList; with ListWin do begin Init; AssignList(ItemList); SetColWidth(15); Win^.SetTitle(' A List With Messages '); Win^.SetSize(20,5,60,20,2); Win^.SetMinSize(20,7); if not FileOk then SetTagging(false); Go; Done; end; ItemList.Done; end. This example works just like DEMLS6.PAS, but a descendant object was created rather than passing a procedure. I know what you are thinking "It's a damn sight easier to pass a procedure!". That's true, and that is precisely why the Toolkit includes the procedure passing alterna- tive. By design, this first taste of OOP was a little simple. If your curiosity has been piqued, review the source code in the unit TOTLIST.PAS. You will see how the base object ListOBJ does all the work, and how the descendant objects ListArrayOBJ and ListLinkOBJ make the objects work for string arrays and linked lists. The totDIR unit discussed in the next chapter extends the ListLinkOBJ and customizes it specifically for displaying files and directories. 9-36 User's Guide -------------------------------------------------------------------------------- Character Hooks The ListOBJ object family provides ways to intercept every key pressed by the user. This allows you to implement your own special hotkeys. Like the Message facility described earlier, there are two different ways to instruct the Toolkit to call a procedure every time a key is pressed -- by passing a procedure, or by creating a descendant object. Using a Character Hook A character hook is an external procedure which is called every time a key or mouse button is pressed. To utilize the character hook facility, all you have to do is create a function following some specific rules, and then call the method SetCharHook to instruct the Toolkit to use your function. For a function to be eligible as a character hook it must adhere to the following rules: Rule 1 The function must be declared as a FAR function. This can be achieved by preceding the function with a {$F+} compiler directive, and following the function with a {$F-} direc- tive. Alternatively, Turbo 6 users can use the new keyword FAR following the function statement. Rule 2 The function must be declared with four (count 'em) passed parameters. Parameter one must be a variable parameter of type word. This parameter indicates which key the user just pressed, and you may change the value of this parameter to substitute a different key. The second and third parameters must be variable parameters of type byte, and they represent the X and Y coordinates of the mouse at the time the key was pressed. The fourth parameter is non-variable, and must be of type longint. This parameter indicates the highlighted item number. Rule 3 The function must return a value of type tListAction. This is an enumerated type which indicates to the Toolkit how to proceed. The members of the enumerated type are: Finish, Refresh and None. If you want the list window to terminate, return Finish. If you have changed, inserted, or deleted any items in the visible list, return Refresh. The Toolkit will then re-display the entire window contents. Normally, how- ever, you will just return None. Rule 4 The function must be at the root level, i.e. the function cannot be nested within another procedure or function. The following function declaration follows these rules: Managing Lists 9-37 -------------------------------------------------------------------------------- {$F+} function MyCharHook(var K:word; var X,Y: byte; HiPick:longint): tListAction; begin ...{function statements} MyCharHook := None; end; {$F-} The following method SetCharHook is then called to instruct the Toolkit to call your function every time a key is pressed: SetCharHook(Func:ListCharFunc); This method is passed the function name of a function declared using the rules outlined above, e.g. SetCharHook(MyCharHook);. The demo program DEMLS8.PAS, listed below, implements both a message hook and a character hook. The character hook is checking for two spe- cial keys. If [KEYCAP] is pressed, a simple help screen is displayed, and if [KEYCAP] is pressed, the topic is changed to the alternative color. program DemoList8; {demls8 - using Message and Character hooks} Uses DOS, CRT, totFAST, totLINK, totLIST, totSTR, totMSG; Var ListWin: ListLinkObj; ItemList: StrDLLOBJ; FileOK: boolean; {$F+} function HelpHook(var K:word; var X,Y: byte; HiPick:longint): tListAc- tion; {} var MsgWin: MessageOBJ; begin HelpHook := None; if K = 315 then begin with MsgWin do begin Init(6,'Kinda Help'); AddLine(''); AddLine('In a real application, this would'); 9-38 User's Guide -------------------------------------------------------------------------------- AddLine('be a help screen, and it would give'); AddLine('help related to item '+IntToStr(HiPick)+'!'); AddLine(''); Show; Done; end; K := 0; end else if K = 316 then {F2 so swap colors} begin ListWin.SetStatus(HiPick,1,not ListWin.GetStatus(HiPick,1)); K := 336; {emulate down cursor} end; end; {HelpHook} function MsgHook(HiPick:longint):string; {} begin MsgHook := 'The Hi Pick is '+IntToStr(HiPick); end; {MsgHook} {$F-} procedure LoadLinkedList; {} var F: text; Line:string; Result: integer; begin with ItemList do begin Init; {$I-} Assign(F,'demls4.txt'); Reset(F); {$I+} FileOK := (IOResult = 0); if not FileOK then Result := Add('File not found') else begin while not eof(F) do begin Readln(F,Line); Result := Add(Line); end; close(F); Managing Lists 9-39 -------------------------------------------------------------------------------- end; end; end; {LoadLinkedList} begin Screen.Clear(white,'░'); {paint the screen} Screen.WriteCenter(25,white,' F1 Help F2 Toggle Color! [Space] Toggle Tag '); LoadLinkedList; with ListWin do begin Init; AssignList(ItemList); SetColWidth(15); SetCharHook(HelpHook); SetMsgHook(MsgHook); SetDualColors(true); Win^.SetTitle(' A Multi-Colored List '); Win^.SetSize(20,5,60,20,2); Win^.SetMinSize(20,7); if not FileOk then SetTagging(false); Go; Done; end; ItemList.Done; end. Figure 9.12 [SCREEN] Using a Character Hook Creating a Descendant Object I think we've had enough OOP for one chapter. Suffice it to say that just like the message hook, the character hook can be implemented by creating a descendant object and replacing a ListLinkOBJ method called CharTask. The demo file DEMLS9.PAS (listed below) shows how to replace both the character hook and the message hook by creating a new descendant object. program DemoListNine; {demls9 - extending the LinkListOBJ object} Uses DOS, CRT, totFAST, totLINK, totLIST, totSTR, totMSG; 9-40 User's Guide -------------------------------------------------------------------------------- Type NewListLinkOBJ = object (ListLinkOBJ) {Methods...} Constructor Init; function MessageTask(HiPick:longint):string; VIRTUAL; function CharTask(var K:word; var X,Y: byte; HiPick:longint): tListAction; VIRTUAL; destructor Done; VIRTUAL; end; {NewListLinkOBJ} Var ListWin: NewListLinkObj; ItemList: StrDLLOBJ; FileOK: boolean; {+++++new object methods+++++} constructor NewListLinkOBJ.Init; {} begin ListLinkOBJ.Init; vMsgActive := true; end; {NewListLinkOBJ.Init} function NewListLinkOBJ.MessageTask(HiPick:longint):string; {} begin MessageTask := 'The Hi Pick is '+IntToStr(HiPick); end; {NewListLinkOBJ.MessageTask} function NewListLinkOBJ.CharTask(var K:word; var X,Y: byte; HiPick:longint): tListAction; {} var MsgWin: MessageOBJ; begin CharTask := none; if K = 315 then begin with MsgWin do begin Init(6,'Kinda Help'); AddLine(''); AddLine('In a real application, this would'); AddLine('be a help screen, and it would give'); AddLine('help related to item '+IntToStr(HiPick)+'!'); AddLine(''); Show; Done; end; K := 0; Managing Lists 9-41 -------------------------------------------------------------------------------- end else if K = 316 then {F2 so swap colors} begin ListWin.SetStatus(HiPick,1,not ListWin.GetStatus(HiPick,1)); K := 336; {emulate down cursor} end; end; {NewListLinkOBJ.CharTask} destructor NewListLinkOBJ.Done; {} begin ListLinkOBJ.Done; end; {NewListLinkOBJ.Done} {+++++end of new object methods+++++} procedure LoadLinkedList; {} var F: text; Line:string; Result: integer; begin with ItemList do begin Init; {$I-} Assign(F,'demls4.txt'); Reset(F); {$I+} FileOK := (IOResult = 0); if not FileOK then Result := Add('File not found') else begin while not eof(F) do begin Readln(F,Line); Result := Add(Line); end; close(F); end; end; end; {LoadLinkedList} begin Screen.Clear(white,'░'); {paint the screen} Screen.WriteCenter(25,white,' F1 Help F2 Toggle Color! [Space] Toggle Tag '); LoadLinkedList; 9-42 User's Guide -------------------------------------------------------------------------------- with ListWin do begin Init; AssignList(ItemList); SetColWidth(15); SetDualColors(true); Win^.SetTitle(' A Multi-Colored List '); Win^.SetSize(20,5,60,20,2); Win^.SetMinSize(20,7); if not FileOk then SetTagging(false); Go; Done; end; ItemList.Done; end.